New in WordPress 3.3: More Useful Help Screens
Note: Post has been updated for 3.3 beta 2
WordPress plugin and theme authors could get something interesting in WordPress 3.3: a somewhat more comprehensive help screen system.
This is actually just a small part of a more long term makeover involving unifying the admin screen code base, but it’s pretty cool nevertheless. Backward compatibility is sorta fuzzy on parts of it at the moment, but not a lot of authors used these functions previously anyway, from what I can tell.
Anyway, I spent an entertaining half hour reworking the help dropdown for my SFC plugin. Here’s what it looks like in 3.3-aortic-dissection right now (note that the look and feel of this will probably change before final):
SFC Help screen in WordPress 3.3
As you can see, the dropdown Help menu moved into the Admin bar (along with lots of other stuff), and has some tabs on the left hand side where you can make different topics and such for different parts of the plugin.
The code for this is actually fairly straightforward, albeit in a sideways sort of way…
First we have to look at the code that adds my options page in the first place. This would work with any of the add_*_page functions, so add_theme_page and such works fine too.
add_action('admin_menu', 'sfc_admin_add_page');
function sfc_admin_add_page() {
global $sfc_options_page;
$sfc_options_page = add_options_page(__('Simple Facebook Connect', 'sfc'), __('Simple Facebook Connect', 'sfc'), 'manage_options', 'sfc', 'sfc_options_page');
add_action("load-$sfc_options_page", 'sfc_plugin_help');
}
This makes an options page, and then uses the assigned identifier for that page to hook the load-* action. This means that when our page is loaded, the sfc_plugin_help function will get called.
function sfc_plugin_help() {
global $sfc_options_page;
$screen = get_current_screen();
if ($screen->id != $sfc_options_page)
return;
Here, we call get_current_screen() to get the current WP_Screen object. The WP_Screen object is new to 3.3, but essentially it encapsulates an admin screen. It’s still under active development, but in the long run, it may make the task of creating admin screens much, much easier.
Anyway, right away, I do one thing and that is to check if the ID of the current screen matches the ID I was given for my options page. If it doesn’t match, then the user isn’t on my screen, and so I return having done nothing at all. This is a sort of belt and suspenders approach, since we shouldn’t be here if load-$sfc_options_page didn’t get called, but it never hurts to be sure.
The next bit is where I add my help screens. Here’s an incomplete sample of that code:
$screen->add_help_tab( array(
'id' => 'sfc-base',
'title' => __('Connecting to Facebook', 'sfc'),
'content' => "HTML for help content",
));
$screen->add_help_tab( array(
'id' => 'sfc-modules',
'title' => __('SFC Modules', 'sfc'),
'content' => "HTML for help content",
));
$screen->add_help_tab( array(
'id' => 'sfc-login',
'title' => __('Login and Register', 'sfc'),
'content' => "HTML for help content",
));
I removed the content for each one to make it clearer. Essentially, I’m just calling the object’s add_help_tab function to add my new tabs to the help screen, one by one. Simple, right?
There’s other useful bits in WP_Screen too, such as adding screen options, adding a right hand side sidebar to the help dropdown, and so forth. I haven’t figured out a use for them yet, but they’re still nice to see.
If you have a complex plugin or theme, might be worth looking into this now. Might reduce your need for end-user support. Maybe. Hard to say. People rarely look at the documentation, but inline help might be worth a shot.
I noticed, while working on a plugin, that add_contextual_help was deprecated but didn’t make the switch because of backwards compatibility. How do you plan to handle this? I’m thinking of just leaving it as is until 3.3 has greater use (and is officially released :P).
The deprecation function call in those was commented out sometime recently, so I think they’re leaving full-conversion until 3.4 or later. So it probably won’t be deprecated in 3.3, just on the verge of deprecation.
I’m not big on backwards compatibility. People should upgrade things. So I plan on having the next major release of SFC just require 3.3. Easy. 🙂
Yeah, I’m not big on backwards compatibility when it prevents me from using a major function I need. But, when it’s just contextual help, I don’t think that’s enough to force an upgrade…yet.
Means, all those plugins which provide contextual help will need to update themselves…..?
Though this one seems better.
If a plugin was using the add_contextual_help() function, then that will continue to work, however it will only do the one-screen of help, not the multiple tabs like this does.
Also, add_contextual_help() may be deprecated in a future version of WordPress, so it’s a good idea to start switching over to the new code as of 3.3.
Thanks for this, Otto!
I was pouring through the new WP_Screen code the other day but was struggling to work out how to use it. The timing of your post was perfect. Cheers!
Thanks for the example of using WP_Screen, but I can’t seem to find any reference to the ‘add_screen_help_and_options’ filter in svn head – nor can I get your method to work as a result. Retrieving the WP_Screen object with
$screen = get_current_screen();at the ‘admin_head’ stage does, however, work fine for me.See, this is what I meant by “may change before final”. That hook isn’t there anymore. It got removed in a revert while things get shuffled around.
See http://core.trac.wordpress.org/changeset/18911/trunk/wp-admin/includes/screen.php
That’s a pretty cool addition to WordPress.
It will be very useful to add help for themes/Plugins this way. Also, it may (slightly?) increase the chances of users actually clicking on theme/Plugin page contextual help if you could optionally override the default ‘Help’ with something else, such as ‘My Plugin Help’ etc.
I don’t think any filters currently exist to easily do this is there?
Update for 3.3-beta 1
To define your help screen tabs you can use any action hook which has global $current_screen object already set and is activated before admin_head action. The one I’ve tried with success is admin_print_scripts.
add_action('admin_print_scripts', 'sfc_plugin_help'); function sfc_plugin_help() { global $sfc_options_page, $current_screen; if ($current_screen->id != $sfc_options_page) return; $current_screen->add_help_tab( array( 'id' => 'sfc-base', 'title' => __('Connecting to Facebook', 'sfc'), 'content' => "HTML for help content", )); $current_screen->add_help_tab( array( 'id' => 'sfc-modules', 'title' => __('SFC Modules', 'sfc'), 'content' => "HTML for help content", )); $current_screen->add_help_tab( array( 'id' => 'sfc-login', 'title' => __('Login and Register', 'sfc'), 'content' => "HTML for help content", )); }Until proper action hook is defined in 3.3 final version you can use admin_print_scripts safely ( I think! ).
Hooking to ‘load-$pagehook‘ action will also work.
I’ve modified the post to show how to hook it up to the load-$hook action hook properly.
[…] version of WordPress, adding help documentation for plugins is really improved and Otto gives a sneak peek at some reworked installation/connection instructions. He also adds a quick fix warning against setting the wrong type of encryption, and the tutorial […]
I’m reworking contextual help for some plugins. To handle the compatibility problem, I’m doing a simple version check.
if ( version_compare($this->wp_version, '3.3' >= 0) ) add_action('admin_head', array($this, 'add_help_tab'));
else add_action('contextual_help', array($this, 'add_contextual_help'), 10, 1 );
Where the ‘add_help_tab’ function calls the old ‘add_contextual_help’ function to get the appropriate content.
Still trying to figure out how to alter existing help though (without editing core files). As of WP 3.3 RC31, class WP_Screen can not be extended, and the existing help is stored in a private variable so you can’t access it directly to make changes using a plugin… Sometimes all you want to do is add a sentence to something, in which case adding another help tab is overkill.
[…] It’ll be interesting to see how different developers put this new functionality to use. Check out this info from Otto on how to set them up. […]
[…] passant, je vous invite à lire l’excellent article d’Otto sur le […]
Might also be worth mentioning that you can clear an existing help tab’s content with:
remove_help_tab( ‘the_id_to_remove’ );
and you can clear ALL help tabs on a page with:
remove_help_tabs(); (no args)
The latter was the only way I could find to completely overwrite default contextual help.
I’m having problems trying to get my help tabs to work; when I call the get_current_screen() function, I get the following error message:
Notice: Trying to get property of non-object in /home/mnich13/public_html/wp-content/plugins/fbttest/fbttest.php on line 103
I’ve tried changing the hook around that calls my help function, but to no avail. The minute I try to reference $screen->id, it blows up.
Any ideas?
Never mind. Sorry I jumped the gun on my problem. Pay no attention to the newbie.
[…] to the previous iteration, the WP 3.3 contextual help is actually quite simple to integrate. Otto Wood wrote a detailed tutorial here.All contextual help-related functionality is handled through the WP_Screen() class, so the first […]
[…] “New in WordPress 3.3: More Useful Help Screens,” Otto on WordPress […]
[…] Adding help to your plugin’s screens (see also the WP Help plugin) […]
[…] “New in WordPress 3.3: More Useful Help Screens,” Otto on WordPress […]
[…] added contextual help to the Themes page in the WordPress Dashboard. It gives theme users a bit more information about […]
[…] “New in WordPress 3.3: More Useful Help Screens37,” Otto on WordPress […]